home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PROGRAM
/
BCCAPP.ARJ
/
GUIDE.DOC
< prev
next >
Wrap
Text File
|
1991-09-15
|
25KB
|
867 lines
(C) 1991 Vision Software, All Rights Reserved.
Address any correspondance to:
Vision Software
3408 Lansdown Drive
Burlington, Ontario, Canada
L7M-1V1
In addition, I may be reach through the following electronic
networks:
GEnie: P.CALVIN
UseNet: phil.calvin@rose.uucp
APPLICATIONS DEVELOPMENT LIBRARY
This library was developed in order to provide serious and
aspiring C++ programmers with an efficient and portable means to
develop data-manipulating applications. With this in mind, we have
attempted to provide services that allow for the creation of an
effective user interface, objects that allow for organized and safe
user input, and finally, indexed record management to control this
input.
DISCLAIMER
Although extensive testing has been performed in an effort to
eliminate errors, the possiblity for errors always remains. This
library is provided in the hope that it will be useful, but without
any warranty of any kind. By using this library, you agree to waive
all claims for damage (however caused) against Vision Software.
LICENSE
I developed this library in order to avoid languages like
Clipper/dBase for simple projects. It is FREE software. I
encourage programmers to distribute the library (including source)
freely. The only restriction I place on its' distribution is that
you may NOT sell the library (other than nominal distribution costs).
You may sell software that was developed using the library. In this
case, I would appreciate receiving a note regarding your software and
its' contents. (This is just a request for my own information, not
required). You may also distribute this software (Source Include)
with applications that you have developed.
HUNGARIAN
Each variable and function within this library is named according
to the "Hungarian" naming convention. Briefly, Hungarian provides
rules that are used in order to "TYPE" variables. Each variable is
made of 3 parts (prefix,tag and qualifier). Of these, only the TAG is
always present, it is the type of the variable. The prefix is used to
modify that type (i.e pointer to X, count of X). The Qualifier is
used to distinguish variables of the same type. Some examples of
hungarian variables are as follows:
sz // Base type, Null terminated string
csz // Counter of strings.
ch // Character
pch // Pointer to a character
rgch // Array of characters
fError // Boolean. fTrue if ERROR
The following tags are used for the classes within this library:
DATABASE dtb;
REPORT rpt;
EDIT edt;
BATCH bat;
WINDOW wnd;
POPUP pop;
DIALOG dial;
PULLDOWN pull;
SCROLL scl;
VSCROLL vscl;
USERS GUIDE
This guide is meant to provide ADL users with an outline of the
techniques needed in order to utilize the various (public) classes.
It is assumed the reader is familiar with C++, as such, we will not
explore the features C++ that allow the creation of this library. In
addition, there is little or no discussion relating to the support
classes that the user generally has no need (or reason) to access
directly.
DATABASE
The ability to save and recall information lies at the heart of
applications programming. Without being able to store information
over time, computers would be little more than expensive calculators.
Unfortunately, data manipulation using traditional systems-oriented
language is quite difficult. On the other hand, while the so-called
"applications" languages provide excellent services to manipulate
data, efficiency in other areas is not generally available.
With the ADL, we provide an efficient and simple to use system
that allows us to manipulate C++ structures. In addition to providing
all required header information, inheritance provides us with a way of
"typing" those records that may be manipulated through the DATABASE.
With this additional feature, the compiler, and (perhaps more
importantly) the user is able to quickly assert which objects are used
for storage.
In order to create an object that may be used with DATABASE,
simply derive it from DBASE. With this, all required information is
available to the system.
Finally, all functions (with the exception of FGotoSz) will
perform normally without opening any index files.
DESCRIPTION
DATABASE(*pdb,cchRec,szFile,fCreate=fFalse)
Summary: Constructor simply initializes the database
system. If fCreate, the file is created if not
found.
CID CidIndexOn(szFileName,*pchKey,cchKey);
Summary: Creates/Opens an index file for the current
database. The key for the index file will be
cchKey bytes at pchKey. The created index then
becomes the currently active index.
BOOL FIndexTo(cid);
Summary: Changes the active index to cid. The database
will then be initialized to the first record (if
available) for the new index.
BOOL FGotoSz(sz,fClose = fFalse)
Summary: Based on the currently active index, FGotoSz()
searches the database for the first key to match.
Answers fFalse if the record cannot be found.
BOOL FMark()
Summary: Marks the current record within the database.
BOOL FGotoMark()
Summary: Goes to the previouslyl established mark.
BOOL FCreate()
Summary: Creates a new record in the database. All indexes
are automatically updated. Will answer fFalse if
some error occurred.
BOOL FFirst()
BOOL FLast()
BOOL FNext()
BOOL FPrevious()
Summary: These functions provide services for sequential
access throughout the file. All will answer
fFalse if the specific operation fails.
BOOL FSave();
BOOL FDelete();
Summary: These functions will save and delete the current
record. NOTE: There is NO confirmation requested
by the system.
DBASE *PdbQuery();
Summary: Not frequently needed, this function will answer
with the pointer to the database object being
manipulated. It is useful in the rare case that
we have the DATABASE, but not the record object.
SZ SzIndex(cid = cidNil);
CCH CchIndex(cid = cidNil);
Summary: Not frequently needed, these functions will answer
with the address and length of the current index
key. If specified, we search the specified index
key.
Example:
//
// Simple exaple program. Traverses database
//
#include <dbase.h>
//
// FOO is our object to manipulate.
//
class FOO : public DBASE
{
CHAR szKey[cchKeyMax];
};
SomeFunction()
{
FOO foo;
DATABASE dtb(&foo,sizeof(foo),"filename",fTrue);
CID cid = dtb.CidIndexOn("filename",foo.szKey,cchKeyMax);
//
// Traverse the entire DATABASE
//
if (dtb.FFirst())
{
do
{
OutputOrWhatever(foo);
}
while (dtb.FNext());
}
}
REPORT GENERATION
Client reports, inventory lists, sales records. Although
similar, traditional programming would require that each report be
written individually. With C++, we may generate standard reports to
the screen or printer with ease.
DESCRIPTION
REPORT(&rdtb);
Summary: Initializes the report.
VOID Title(sz,al = alCentre);
Summary: Creates a title for the report. The alignment of the title
is al (alLeft/alCentre/alRight)
VOID Entry(col,sz,cch,szTitle = szNil);
Summary: Creates a field for the report. The entry will be
taken from sz for each record. If desired, a
title may be specified that will be placed at the
top of each page.
VOID SetFilterTo((*pfnFUse)(DBASE *pdb));
Summary: The report may be filtered in order to limit the
records that are viewed. pfnFUse must answer
fTrue if the record is to be included.
VOID Generate(fForward = fTrue,fPrinter = fFalse);
Summary: Creates the report. Normally the report will
traverse the Database forward and place the output
to the screen.
USER INPUT
Complex user input may be simplified by dividing all required
information into "Fields". These fields may then be designed to
accept specific data types. By this technique, complex input
sequences (Such as entering client information) may be presented in an
effective manner that any user will understand.
The EDIT class provides the user with these very services. Each
field may be individually validate using a variety of methods. These
range from simple "picture" validation up to set validation.
DESCRIPTION
EDIT(fConfirm = fFalse,szTitle = szNil);
Summary: Creation of the EDIT. May specify a title for the
window and whether the user should be queried
before terminating.
VOID Title(row,col,sz);
Summary: Title fields may be used to intersperse messages
or information within the window that may not be
modified.
VOID Field(row,col,szMsg,sz,szPic,szHelp=szNil,szDefault=szNil);
Summary: Specifies an editable field for the user. In this
case, the picture is a NULL terminated string of
pictures (ex: "XXX999"). The length of this
string is used to determine the length of the
field. The following pictures are available:
X- Any printable character
9- Digits
A- Upper case letters, any other char
a- Lower case letters, any other char
U- Upper case letters only
L- Lower case letters only
N- Upper case Letters, Numbers
n- Lower case Letters, Numbers
VOID Field(row,col,szMsg,sz,ch,cch,szHelp=szNil,szDefault=szNil);
Summary: Specifies an editable field for the user. The
picture is the character ch, the length of the
field is given by cch.
VOID Field(row,col,szMsg,sz,cch,szHelp,cent,pent,centDefault);
Summary: Specifies an editable field for the user. In
order for the input to be valid, it must match an
entry within the ENT (see POPUPs). The length of
the field is the length of the longest element of
the ENT.
VOID Read();
Summary: Starts the EDIT process. Centers a window on the
screen and activates the field editor.
VOID Delimiters(chLeft='[',chRight=']');
Summary: Allows the programmer to change the default field
delimiters.
BATCH USER INPUT
Combining EDIT with our DATABASE class, we have provided BATCH
user input. With this, the user may (manually) enter lists of
information painlessly. Such lists could include client lists,
inventory lists or whatever.
BATCH is publicly derived from EDIT. As such, creation of fields
is identical. By specifying one (or more) index fields, the system
will maintain ordering based upon those fields. An IndexSelector may
be provided to allow the user to switch indexes during the edit.
DESCRIPTION
BATCH(*pdb,cch,szFile,szTitle = szNil,(*pfnCreate)(DBASE *) = Nil);
BATCH(&rdtbOriginal,szTitle = szNil,(*pfnCreate)(DBASE *) = Nil);
Summary: Opens the DATABASE (creates if necessary) and
initializes the EDIT. pfnCreate is called before
created a new record.
VOID Index(row,col,szFile,szMsg,sz,chPic,cch,szHelp = "",szDefault = szNil);
VOID Index(row,col,cid,szMsg,chPic,szHelp = "",szDefault = szNil);
Summary: Create an index field. All parameters are
identical to EDIT field, with the exception of the
index file name. If the database was already opened,
the user may provide the cid instead of the index file
name.
VOID IndexSelector(row,col,szMsg,cent,pent,centDefault = centNil);
Summary: Creates a field that the user may edit in order to
change the active index file. The library will
Assert if this method is called more than once per
object.
//
// Demo of Batch User Input
//
#include <batch.h>
struct CLIENT : public DBASE
{
CHAR rgchName[30];
CHAR rgchAddr[30];
...
}
//
// Create client lists..
//
VOID EditClient()
{
CLIENT cli;
BATCH bat(&cli,sizeof(cli),"clients","Edit Client Lists");
//
// Setup fields...
//
bat.Index(1,1,"clients","Name :",cli.rgchName,'X',30);
bat.Field(3,1,"Address :",cli.rgchAddr,'X',30);
...
//
// And, execute read..
//
bat.Read()
}
WINDOWS
Used by nearly every public class, WINDOWs provides the
programmer with an opportunity to present complex information in an
organized, understandable fashion.
DESCRIPTION
WINDOW(row1,col1,row2,col2,coFore,coBack,sz=szNil,fScroll=fFalse);
WINDOW();
Summary: A window may be created by specifying all
dimensions and colours or none at all. If none,
the system default is used.
VOID Open();
VOID Close();
Summary: Creates the window on screen, and conversely,
removes it.
VOID Move(row,col);
Summary: An opened window may be moved to any position on
the screen. If an attempt is made to move the
window OFF the screen, the system will stop the
window at the edge.
VOID Cls();
VOID ClearRow(rowClear);
VOID ClearCol(colClear);
Summary: Clears the window or portions of it.
VOID SetScrollCol(colLeft,colRight);
VOID SetScrollRow(rowTop,rowBottom);
Summary: Using these functions, the programmer may set
individual scroll regions within each window. The
default is to scroll the entire window.
VOID ScrollDrow(drow);
VOID ScrollDcol(dcol);
Summary: These functions provide the programmer with manual
control over a windows scrolling. Even if
automatic scroll is turned off, these functions
will perform normally.
ROW RowQuery();
COL ColQuery();
Summary: These functions will answer with the current
cursor position.
VOID SetRowCol(row,col);
Summary: Manually adjust the cursor position. The next
output will take place here.
VOID Say(sz,coFore = coError,coBack = coError);
VOID SayAt(row,col,sz,coFore=coError,coBack=coError);
VOID SayHot(row,col,sz,cch,coFore=coError,coBack=coError);
VOID SayCentered(row,sz,coFore=coError,coBack=coError);
VOID PutCh(ch,coFore=coError,coBack=coError);
Summary: These output routines may be used to output text
to the (opened) windows. Each method will update
the cursor position after and scroll the window as
necessary and desired.
HELP SYSTEM
Even the simplest program is useless if the user is unable to
determine the correct action. For that reason, we provide a simple to
use help system. The bottom row of the screen is off-limits to the
application. It is instead used by the Help class to provide quick
help to the user.
DESCRIPTION
HELP(sz);
Summary: To use the simple help system, create an object of
type HELP. With that, the bottom line of the
screen will be updated. Once the object is
destroyed, the original message will return.
VOID Replace(sz);
Summary: The help text may be adjust after construction as
many times as necessary.
MENUS
Selection boxes are an effective technique that allows the
programmer to "prevent" user mistakes. Our menu system is based upon
the following ENT structure.
In general, each selection box will be an array of ENTs. These
structures include everything to describe an individual menu entry.
For each ENT to be valid, only the text for the menu entry needs to be
valid. All other fields may be ignored if not needed.
struct ENT
{
SZ sz; // Text for menu entry
CCH cchHotKey; // Index into sz for Hotkey
VOID (*pfnFunction)(VOID);// Function for selected item
SZ szQuickHelp; // Text at bottom row of the screen
CENT centNext; // Number of entries in Sub-Menu
ENT *pentNext; // Sub-Menu may be linked here
POPUPS
The super class for our menu system is POPUPs. Upon creation,
popups are fixed in size. Their height will be exactly the size of
the number of Entries. Thus, each option will be displayed when the
popup is on screen.
All classes that follow are derived from POPUP, as such, each
will have the functionality provided from within that super class.
DESCRIPTION
POPUP(row,col,cent,pent,sz=szNil);
Summary: Initializes the popup. The program will Assert if
pent does not contain a valid address, or if cent
is greater than the height of the screen.
CENT CentGet();
Summary: Activates the menu. The program answers with the
number of the entry that was selected. If the
user ESCaped, centError is answered. If that
entry has a Sub-Menu, another popup is presented
to the right of the original. If the selected
entry has a valid function address, that function
is called before returning.
PULLDOWN MENU BARS
By linking together several POPUPs, the Pulldown manager provides
use with the traditional Pulldown menus. The Menu bar is described as
an array containing the following information:
struct BAR
{
SZ sz; // Text for heading
CCH cchHotKey; // Offset in sz for "HotKey"
CENT cent; // Number of entries in menu
PENT pent; // Array of menu entries.
};
DESCRIPTION
PULLDOWN(row,cbar,*pbar);
Summary: Creates a pulldown bar to be displayed at row
(Usually 1). The program will Assert if pbar does
not contain a valid address.
VOID ShowBar();
Summary: Displays the Menu bar at the prescribed row.
CD CdGet();
Summary: Activates the menu-bar. The program will answer
with the key that caused the system to return.
ESC terminates without selection. Any other key
means a valid selection took place.
DIALOG BOXES
Dialog boxes are handy if the user is required to answer some
question. Usually there will be two or three answers, the user simply
needs to select ONE of them.
DESCRIPTION
DIALOG(sz,cent,pent);
Summary: Creates the dialog box. Sz is the message to be
presented.
CENT CentGet();
Summary: Presents the dialog. Again, centError is return
if the user presses ESC.
SCROLL BOXES
Unlike regular POPUPs, the number of entries in a SCROLL box
exceeds that of the size. Because of this, the selector scrolls up
and down as the user moves the cursor.
DESCRIPTION
SCROLL(row,col,cent,pent,centMac,sz=szNil)
Summary: Creates a new scroll box. This class is publicly
derived from POPUP, as such, its' use is
identical.
VIRTUAL SCROLL BOXES
Similar to Scroll Boxes, the number of entries within a Virtual
scroll box usually exceeds its' size. In this case, the entries are
taken from the KEY fields within a database. The number of entries
will be equal to the number of records within the database.
DESCRIPTION
VSCROLL(row,col,centView,&rdtb,sz,cch,szTitle = szNil);
Summary: Creates a Virtual scroll box. Again, this is
publicly derived from POPUP. Upon termination,
the DATABASE will be left pointing to the selected
record.
LIBRARY DECLARATIONS
These declarations are provided for reference only. They contain
only public methods and are intended to reinforce the rest of this
manual. For a complete reference, including all typedefs etc, please
refer to the files in the inc/ subdirectory.
:
/*
* Public utility routines.
*/
EXTERN BOOL FAskSz(SZ sz,SZ szHelp = szNil); // Asking Yes/No
EXTERN VOID SaySz(SZ sz,SZ szHelp = szNil); // Message to user
EXTERN VOID ErrorSz(SZ sz,SZ szHelp = szNil); // Error message to user
EXTERN CD CdInput(VOID); // Input Interface
/*
* Global variables to provide run-time dimensions for the screen..
*/
EXTERN ROW rowGlobalWindowBottom;
EXTERN COL colGlobalWindowRight;
/*
* Standard menu. Usually appears first under "System" header
*/
EXTERN ENT pentVision[];
/*
* Context-sensitive help system
*/
class HELP
{
public:
HELP(SZ sz);
~HELP();
VOID Replace(SZ sz);
};
/*
* Windowing system.
*/
class WINDOW
{
public:
WINDOW(ROW row1,COL col1,ROW row2,COL col2,CO coFore,CO coBack,SZ
sz=szNil,BOOL fScroll = fFalse);
WINDOW(VOID);
~WINDOW(VOID);
VOID Draw(VOID);
VOID Open(VOID);
VOID Close(VOID);
VOID Move(ROW row,COL col);
ROW RowQuery(VOID);
COL ColQuery(VOID);
VOID Cls(VOID);
VOID ClearRow(ROW rowClear);
VOID ClearCol(COL colClear);
VOID ScrollDrow(ROW drow);
VOID ScrollDCol(COL dcol);
VOID SetScrollCol(COL colLeft,COL colRight);
VOID SetScrollRow(ROW rowTop,ROW rowBottom);
VOID SetRowCol(ROW row,COL col);
VOID Say(SZ sz,CO coFore = coError,CO coBack = coError);
VOID SayAt(ROW row,COL col,SZ sz,CO coFore = coError,CO coBack =
coError);
VOID SayHot(ROW row,COL col,SZ sz,CCH cch,CO coFore = coError,CO
coBack = coError);
VOID SayCentered(ROW row,SZ sz,CO coFore = coError,CO coBack =
coError);
VOID PutCh(CHAR ch,CO coFore = coError,CO coBack = coError);
};
/*
* Database.
*/
class DATABASE : private ACCESS
{
public:
DATABASE(DBASE *pdb,CCH cchRecord,SZ szFileName,BOOL fCreateFile =
fFalse);
~DATABASE();
BOOL FSave();
BOOL FMark();
BOOL FGotoMark();
BOOL FDelete();
BOOL FFirst();
BOOL FLast();
BOOL FNext();
BOOL FPrevious();
BOOL FCreate();
BOOL FGotoSz(SZ sz,BOOL fMatchIfClose = fFalse);
BOOL FGotoRec(REC rec);
BOOL FIndexTo(CID cid);
CID CidIndexOn(SZ szFileName,CHAR *pchKey,CCH cchKey);
DBASE *PdbQuery();
SZ SzIndex();
CCH CchIndex();
};
/*
* Edit Class Specification..
*/
class EDIT
{
public:
EDIT(BOOL fConfirm = fFalse,SZ sz = szNil);
~EDIT();
VOID Read();
VOID Title(ROW row,COL col,SZ sz);
VOID Field(ROW row,COL col,SZ szMsg,SZ sz,SZ szPic,SZ szHelp =
szNil,SZ szDefault = szNil);
VOID Field(ROW row,COL col,SZ szMsg,SZ sz,CHAR ch,CCH cch,SZ szHelp
= szNil,SZ szDefault = szNil);
VOID Field(ROW row,COL col,SZ szMsg,SZ sz,CCH cch,SZ szHelp,CENT
cent,PENT pent,CENT centDefault = centNil);
VOID Delimiters(CHAR chL='[',CHAR chR=']');
};
/*
* Batch field editing.
*/
class BATCH : public EDIT
{
public:
BATCH(DBASE *pdb,CCH cch,SZ szFile,SZ szTitle = szNil);
VOID Index(ROW row,COL col,SZ szFile,SZ szMsg,SZ sz,CHAR chPic,CCH
cch,SZ szHelp = "");
VOID IndexSelector(ROW row,COL col,SZ szMsg,CENT cent,PENT pent,CENT
centDefault = centNil);
};
/*
* Report Generation
*/
class REPORT
{
public:
REPORT(DATABASE &rdtb);
~REPORT();
VOID Entry(COL col,SZ sz,CCH cch,SZ szTitle = szNil);
VOID SetFilterTo(BOOL (*pfnFUse)(DBASE *pdb));
VOID Generate(BOOL fForward = fTrue,BOOL fPrinter = fFalse);
};
/*
* Popup Superclass. Base class for all menus
*/
class POPUP
{
public:
POPUP(ROW row,COL col,CENT cent,PENT pent,SZ sz=szNil);
CENT CentGet();
};
/*
* Scroll boxes
*/
class SCROLL : public POPUP
{
public:
SCROLL(ROW row,COL col,CENT cent,PENT pent,CENT centView,SZ
sz=szNil);
};
/*
* Virtual scroll boxes
*/
class VSCROLL : public SCROLL
{
public:
VSCROLL(ROW row,COL col,CENT centView,DATABASE &rdtb,SZ sz,CCH
cch,SZ szTitle = szNil);
};
/*
* The pulldown system uses each menu as a special case of the
* Popup system we just declared...
*/
class PULLDOWN : private POPUP
{
public:
PULLDOWN(ROW row,CBAR cbar,BAR *pbar);
VOID ShowBar();
CD CdGet();
};
/*
* Dialog boxes.
*/
class DIALOG : public POPUP
{
public:
DIALOG(SZ sz,CENT centMax,PENT pent);
~DIALOG();
};